AI 编程最佳实践
用 AI 写代码不难，难的是持续写出好代码。
大多数人在接触 AI 编程工具之后，很快会遇到同一类问题：前几次效果不错，但随着项目变复杂，AI 开始乱改代码、忘记上下文、生成无法维护的东西。问题不在工具本身，而在于没有建立一套稳定的工作方式。
这篇笔记整理了一套系统性的 AI 编程方法论，核心思路来自软件工程师 Chris Dzombak 的实践经验1，适用于 Claude Code 以及大多数 AI 编程场景。
一、为什么需要最佳实践
AI 辅助编程的效率提升是真实的：
| 人群 | 效率提升 | 来源 |
|---|---|---|
| 整体开发者平均 | 25–26% | MIT Sloan2 |
| 初级开发者 | 27–39% | Harvard Business School3 |
| 资深开发者 | 8–13% | Harvard Business School3 |
| 工作质量提升 | 约 40% | Harvard Business School3 |
但这些数字有个前提：AI 被正确使用。没有规范的情况下，AI 同样能以极快的速度生成难以维护的代码、引入隐蔽的 bug、或者反复走弯路。
真正的差距不在于谁更懂 Prompt 技巧，而在于谁能系统性地调教 AI、建立清晰工作流程、始终对代码质量负责。
二、核心理念
在开始任何操作之前，先确立几条基本原则。这些原则决定了 AI 生成代码的整体风格和可维护性。
增量优于全部重构
把任务拆成小步骤，每一步都要可编译、可测试、可验证。
不要让 AI 一次性重写整个模块。大范围的改动很难审查，出问题也很难定位。小步骤的每一次提交都是一个稳定的检查点。
清晰优于聪明
优先考虑可读性和可维护性，不要追求"巧妙"的实现。
AI 很擅长生成看起来高明的代码，但"聪明"的代码往往意味着六个月后没人能看懂，包括你自己。可读性是团队协作的基础，也是代码长期存活的前提。
先读懂现有代码，再开始实现
让 AI 在动手之前先理解项目上下文，而不是直接开始生成。
这一步经常被跳过，后果是 AI 写出来的代码风格不一致、忽略了已有的抽象层、甚至重复造轮子。先读、再写，是一个简单但有效的习惯。
三、标准工作流程
一个可靠的工作流不应该因为"用了 AI"而改变，反而要更严格地执行：
规划 → 写测试 → 实现 → 重构 → 提交
规划：明确目标、输入、输出和边界条件，不要急着让 AI 开始写代码。
写测试：在实现之前先写测试用例，让 AI 有明确的验收标准可以对齐。测试也是最有效的护欄——它们不会因为 AI 换了一种写法而自动变松。
实现：让 AI 生成代码，但把输出当作草稿，不是最终版。
重构：审查生成的代码，清理不必要的复杂度，确保风格一致。
提交：每个小步骤独立提交，保持 git 历史清晰可追溯。
决策优先级
当实现方式存在取舍时，按这个顺序判断：
可测试性 > 可读性 > 一致性 > 简单性
四、用 CLAUDE.md 给 AI 植入工程规范
这是整套方法论最有杠杆效应的部分。
CLAUDE.md 是 Claude Code 的项目级配置文件，放在项目根目录，每次会话开始时自动加载。它相当于给 AI 一份"入职规范"——让它在每次工作前就知道这个项目的开发哲学、工作流程和边界。
文件层级
| 位置 | 作用范围 |
|---|---|
~/.claude/CLAUDE.md | 全局默认，所有项目通用 |
项目根目录/CLAUDE.md | 当前项目规范 |
父目录 CLAUDE.md | 多项目共享规范（monorepo 场景） |
优先级从低到高，项目级配置会覆盖全局默认。
该写什么
开发哲学：明确这个项目的基本原则，例如"增量优于重构"、"清晰优于聪明"。
标准工作流程：写明每次任务的执行顺序，比如"先规划，再写测试，再实现"。
卡住时的预案：这一条经常被忽视，但非常重要。规定 AI 在失败时应该怎么做，而不是让它无限重试：
## 卡住时的处理方式
最多尝试 3 次失败后必须停止，然后：
1. 记录失败的原因和已尝试的方案
2. 研究替代方案，不要重复同样的思路
3. 向用户说明当前状态，等待指引
决策优先级：把"可测试性 > 可读性 > 一致性 > 简单性"写进去，让 AI 在面临取舍时有明确参考。
禁止行为：列出不允许的操作，比如"不要修改 build/ 目录"、"不要在没有测试的情况下重构"。
一个写好的 CLAUDE.md，等于把你作为工程师的判断力持久化到了工具里。
五、上下文管理
AI 的"注意力"是有限的。长会话中，它会逐渐忘记早期的约束、偏离项目目标、开始重复已经讨论过的内容。这个现象叫上下文漂移。
使用 /compact 命令
Claude Code 提供 /compact 命令，可以在不丢失核心信息的情况下压缩会话历史。
适合在以下时机使用：
- 一个功能阶段完成后
- 感觉 AI 开始"绕圈子"或忘记早期约束时
- 会话明显变长，响应开始变慢时
注意：不要直接清除所有历史，
/compact是保留摘要、压缩细节，而不是清空。
任务拆分策略
每次会话专注于一个具体的小目标，完成后开新会话。把"实现整个用户模块"拆成多个独立任务，每个任务有清晰的输入和输出。
这样做有两个好处：上下文保持干净，每个阶段也更容易审查和回滚。
六、常见陷阱
过度依赖，技能退化
AI 能快速生成代码，但理解代码的责任在你。如果你不理解 AI 写了什么，就无法判断它是否正确，也无法在出问题时调试。
保持对底层原理的理解，不是因为 AI 不可靠，而是因为判断力需要知识基础。
上下文漂移
在长时间会话中，AI 可能会忘记项目目标、之前达成的决定，或者开始偏离约定的风格。
解决方式：定期使用 /compact，重要约定写入 CLAUDE.md，不要依赖会话记忆来传递关键信息。
AI 输出是起点，不是终点
AI 生成的代码是草稿，需要人工审查。常见问题包括：
- 边界条件处理不完整
- 引入了不必要的依赖
- 风格与项目其他部分不一致
- 测试覆盖了表面，但遗漏了关键路径
不要因为"代码能跑"就直接合并。能跑和写得好是两件事。
解决方案同质化
AI 倾向于给出"最常见"的解法，而不是最适合当前上下文的解法。在有特殊约束或技术背景的项目里，要明确告诉 AI 这些约束，而不是期望它自己推断。
七、实践建议
你是责任方，AI 是执行工具。 AI 写的代码，bug 是你的，架构问题是你的，安全漏洞是你的。这不是在贬低 AI，而是在强调：审查和判断不能外包。
清晰的指令比聪明的 Prompt 更有效。 与其学各种 Prompt 技巧，不如把任务描述清楚：明确输入、期望输出、边界条件、不允许的操作。结构化的输入带来结构化的输出。
护栏先于速度。 在提速之前，先建立单元测试、明确接口定义、使用强类型约束。护栏不是在拖慢你，而是在保证加速时不翻车。
系统优于意志力。 把工程规范写进 CLAUDE.md，把工作流程固定下来，把常见约束文档化。依赖系统，不要每次都重新解释一遍规则。
参考资料
- Chris Dzombak — Claude Code Tips · tenten.co · 2025↩
- Dell'Acqua et al. — Navigating the Jagged Technological Frontier · Harvard Business School · 2023↩
- Brynjolfsson et al. — Generative AI at Work · MIT Sloan / NBER · 2023↩